QTML Compatibility1

The utility functions described in this section implement the QuickTime Media Layer (QTML) and perform miscellaneous tasks to make Windows programs compatible with QuickTime.

InitializeQTML

InitializeQTML initializes the QuickTime Media Layer.



 
OSErr InitializeQTML(long flags);

flags: Option flags:

DISCUSSION

Use InitializeQTML to initialize a QTML session, before calling EnterMovies . You should not make this call from a QuickTime component such as an image decompressor; it is provided only for host applications.

TerminateQTML

TerminateQTML terminates the QuickTime Media Layer.



 
void TerminateQTML(void);

DISCUSSION

Use TerminateQTML to terminate a QTML session after calling ExitMovies . You should not make this call from a QuickTime component, such as an image decompressor; it is provided only for host applications.

QTMLCreateMutex

QTMLCreateMutex creates a synchronization object to facilitate mutually exclusive access to a Windows data structure.



 
QTMLMutex QTMLCreateMutex(void);

function result: A mutex object.

DISCUSSION

The QTMLCreateMutex function creates a mutex object for guarded access to data structures and routines that require mutually exclusive access. In a multithreaded preemptive environment, such as Windows NT, you can use the various mutex utility functions such as QTMLGrabMutex to protect a shared resource from simultaneous access by multiple threads or processes. Mutex objects are used throughout QTML to provide such protection.

QTMLDestroyMutex

QTMLDestroyMutex deallocates a synchronization object created by the QTMLCreateMutex function.



 
void QTMLDestroyMutex(QTMLMutex theMutex);

theMutex: A mutex object.

DISCUSSION

Call the QTMLDestroyMutex function to deallocate the mutex object created by QTMLCreateMutex .

QTMLGrabMutex

QTMLGrabMutex confers ownership of a mutex created by the QTMLCreateMutex function.



 
void QTMLGrabMutex(QTMLMutex theMutex);

theMutex: A mutex object.

DISCUSSION

Call the QTMLGrabMutex function when you require exclusive ownership of the resource guarded by the mutex. This function will return when you have gained this ownership. In the case where another thread or process holds the mutex, this function waits until that process or thread relinquishes control. If you need to determine if you can grab the mutex, without actually grabbing it, call QTMLTryGrabMutex .

QTMLTryGrabMutex

QTMLTryGrabMutex determines if you would be able to get immediate ownership of a mutex created by QTMLCreateMutex .



 
Boolean QTMLTryGrabMutex (QTMLMutex theMutex);

theMutex: A mutex object.

DISCUSSION

Call the QTMLTryGrabMutex function when you need to preflight a QTMLGrabMutex call. It returns true if you are able to immediately grab the mutex, via the QTMLGrabMutex call, without having to wait. Under normal circumstances, you should not need to make this call.

QTMLReturnMutex

QTMLReturnMutex releases ownership of a QTMLMutex object.



 
void QTMLReturnMutex (QTMLMutex theMutex);

theMutex: A mutex object.

DISCUSSION

Call the QTMLReturnMutex function to balance the call to QTMLGrabMutex when you are ready to relinquish control of the mutex and corresponding shared resource. By making this call you allow other processes or threads waiting for the release of this mutex to gain access.

QTMLCreateSyncVar

QTMLCreateSyncVar creates a synchronization variable, used to provide guarded access to resources shared across threads and processes.



 
QTMLSyncVarPtr QTMLCreateSyncVar(void);

function result: A pointer to a synchronization variable.

DISCUSSION

Call the QTMLCreateSyncVar function to create a synchronization variable that allows for mutually-exclusive access to resources. The synchronization variable routines use atomic tests to ensure that the portions of the routines that perform the testing cannot be interrupted during the test.

QTMLDestroySyncVar

QTMLDestroySyncVar releases ownership of a synchronization variable.



 
void QTMLDestroySyncVar(QTMLSyncVarPtr p);

p: A pointer to a synchronization variable.

DISCUSSION

Call the QTMLDestroySyncVar function to deallocate the QTMLSyncVar object created by QTMLCreateSyncVar .

QTMLTestAndSetSyncVar

QTMLTestAndSetSyncVar performs a one-shot atomic test and set operation of a QTMLSyncVar object.



 
long QTMLTestAndSetSyncVar(QTMLSyncVarPtr p);

p: A pointer to a synchronization variable.
function result: 0 if successful.

DISCUSSION

Call the QTMLTestAndSetSyncVar function to perform a single test and set operation on the QTMLSyncVar object. The function returns 0 if you have acquired the lock.

QTMLWaitAndSetSyncVar

QTMLWaitAndSetSyncVar acquires the lock for a QTMLSyncVar object,



 
void QTMLWaitAndSetSyncVar(QTMLSyncVarPtr p);

p: A pointer to a synchronization variable.

DISCUSSION

Call the QTMLWaitAndSetSyncVar function to acquire the lock corresponding to a QTMLSyncVar object. This function will wait, yielding CPU time to other threads, until the lock is acquired.

QTMLResetSyncVar

QTMLResetSyncVar reset the lock for a QTMLSyncVar object.



 
void QTMLResetSyncVar(QTMLSyncVarPtr p);

p: A pointer to a synchronization variable.

DISCUSSION

Call the QTMLResetSyncVar function to relinquish the lock obtained from a previous call to QTMLWaitAndSetSyncVar .

QTMLRegisterInterruptSafeThread

QTMLRegisterInterruptSafeThread registers a thread of execution that is allowed to make interrupt-safe calls.



 
void QTMLRegisterInterruptSafeThread(unsigned long threadID, void *info);

threadID: Thread ID of the calling thread. This value is obtained by calling the Win32 GetCurrentThreadId function.
info: Thread information. This value is obtained by calling the Win32 GetCurrentThread function.

DISCUSSION

The QTML function dispatcher includes a mechanism that prevents not only the Toolbox from getting reentered but also allows certain APIs to be callable at interrupt time. On the Macintosh, these calls are listed in Inside Macintosh, and require that the calling code not allocate, move, or purge memory. On Windows, threads that emulate interrupt handlers need to register with QTML, by calling the QTMLRegisterInterruptSafeThread function, so that API calls made from this thread are not blocked. You should make this call at the top of your thread main routine.

QTMLUnregisterInterruptSafeThread

QTMLUnregisterInterruptSafeThread unregisters a thread of execution.



 
void QTMLUnregisterInterruptSafeThread(unsigned long threadID);

threadID: Thread ID of the calling thread. This value is obtained by calling the Win32 GetCurrentThreadId function.

DISCUSSION

Use the QTMLRegisterInterruptSafeThread function to unregister an interrupt safe thread previously registered by the QTMLRegisterInterruptSafeThread function. You should make this call at the bottom of your thread main routine, just before the exit.

QTMLYieldCPU

QTMLYieldCPU yields time to other threads while your code is in a tight loop.



 
void QTMLYieldCPU(void);

DISCUSSION

Use the QTMLYieldCPU function from within tight loops to yield time to other threads. Using this function is similar to calling SystemTask from within a Macintosh event loop.

QTMLYieldCPUTime

QTMLYieldCPUTime yields time to other threads and specifies the sleep time while in a tight loop.



 
void QTMLYieldCPUTime(long milliSecsToSleep, unsigned long flags);

milliSecsToSleep: Number of milliseconds to sleep before returning to the caller.
flags: Option flags:

DISCUSSION

Use the QTMLYieldCPUTime function from within tight loops to yield time to other threads. This function differs from QTMLYieldCPU in that you can specify the time to sleep as well as optionally have QTML process Win32 messages while waiting for the yield time to expire.

QTMLSetWindowWndProc

The QTMLSetWindowWndProc routine allows you to specify an application-defined window procedure (WNDPROC ) which is called by QTML after QTML processes the message for the HWND .



 
void QTMLSetWindowWndProc(WindowPtr wPtr, void *windowProc);

wPtr: Specifies the Macintosh window to hook. This must have been created via NewCWindow , NewWindow , or as a result of calling CreatePortAssociation on a native HWND .
windowProc: A Windows WNDPROC procedure. For a detailed description of the WNDPROC procedure, check your Win32 documentation.

DISCUSSION

The QTMLSetWindowWndProc routine is useful if you want to perform some special Windows processing of the native messages that Windows sends to your WindowPtr .

QTMLGetWindowWndProc

The QTMLGetWindowWndProc routine returns the WNDPROC previously specified in QTMLSetWindowWndProc . It returns NULL if no application-defined WNDPROC is set.



 
void *QTMLGetWindowWndProc(WindowPtr);

wPtr: Specifies the Macintosh window to hook. This must have been created via NewCWindow , NewWindow , or as a result of calling CreatePortAssociation on a native HWND .